%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 
%  $Id: sendmail.tex,v 1.14 1994/06/03 05:47:47 vince Exp vince $
%
%
%  Changes since v1.10:
%	- included Olaf's formatting changes to set up OR+A formats
%	- Olaf matched the examples with the rest of the NAG examples
%		(done except for the installing/testing section
%			which was still under construction)
%	- wrote the installing and testing section.  Please take a
%		look at the formatting in particular.  My brain must
%		me dead but those darn '-' characters are driving me
%		nutso.  Also I'm not certain if the bullet-list looks
%		ok since there are a lot of bullets in the section.
%
% To-do:
% 	- clean up examples and formatting in the 'installing and 
%		testing' section to match the rest of the book
%	- I'm not certain the sendmail.m4 example is totally right.
%		please see the comments in the text.
%	- The inevitable typos/grammar edits :-)
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% This document requires no approvals other than ours for 
% publications, but at this time it is still a draft.
% 
% I don't see any problem in you guys sending edits/comments/etc. to
% both the work and home addresses at this time. 
% 
% 		Vince Skahan
% 
%   Home: +1 206 661 9265   vince@victrola.wa.com (primary)
%                           vince@halcyon.com     (alternate)
%
%   Work: +1 206 662 4407   vince@atc.boeing.com
% 
% This document assumes that the reader already knows or has been told
% in either previous chapter(s) of the fact that there are several major
% system mail transport agents (sendmail5.65, smail3.1.28,
% sendmail8.6.5, and sendmail5.67b+IDA1.5) 
%
% this document only references sendmail+IDA.
% 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \documentstyle[linuxdoc,private]{article}
% \title{Sendmail+IDA}
% \author{Vince Skahan}
% \years{1994}

% \begin{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Make the title
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \maketitle

\chapter{Sendmail+IDA}
\label{sendmail}

\index{configuring!sendmail@\prog{sendmail}|(}
\index{sendmail@\prog{sendmail}|(}

% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Moved to the foreword
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \section{About the Author}
% 
% Vince Skahan (\email{vince@victrola.wa.com}) has been administering
% large numbers of unix systems since 1987 and currently runs sendmail+IDA
% on approximately 300 unix workstations for over 2000 users.
% 
% He admits to losing considerable sleep from editing quite a few
% \file{sendmail.cf} files 'the hard way' before discovering sendmail+IDA
% in 1990. He also admits to anxiously awaiting the delivery of the first
% perl-based version of sendmail for even more obscure fun.
% 
% \section{Acknowledgements}
% 
% Thanks go to Neil Rickert and Paul Pomes for lots of help over the years
% regarding the care and feeding of sendmail+IDA and to Rich Braun for
% doing the initial port of sendmail+IDA to \linux.  The biggest thanks by far
% go to my wife Susan for all the support on this and other projects.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Introductory part
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction to Sendmail+IDA}

It's been said that you aren't a \emph{real} Unix system administrator until
you've edited a \file{sendmail.cf} file.  It's also been said that you're
crazy if you've attempted to do so twice\term{:-)}

Sendmail is an incredibly powerful program.  It's also incredibly difficult
to learn and understand for most people.  Any program whose definitive
reference (\emph{Sendmail}, published by O'Reilly and Associates) is 792 pages
long quite justifiably scares most people off.

\index{sendmail.cf@\file{sendmail.cf}|see {\prog{sendmail}, \file{sendmail.cf}}}
\index{sendmail@\prog{sendmail}!sendmail.cf@\file{sendmail.cf}}
Sendmail+IDA is different.  It removes the need to edit the always cryptic
\file{sendmail.cf} file and allows the administrator to define the
site-specific routing and addressing configuration through relatively easy to
understand support files called \emph{tables}.  Switching to sendmail+IDA can
save you many hours of work and stress.

Compared to the other major mail transport agents, there is probably nothing
that can't be done faster and simpler with sendmail+IDA.  Typical things that
are needed to run a normal UUCP or Internet site become simple to accomplish.
Configurations that normally are extremely difficult are simple to create and
maintain.

At this writing, the current version of \file{sendmail5.67b+IDA1.5} is
available via anonymous FTP from \host{vixen.cso.uiuc.edu}.  It compiles
without any patching required under \linux.

All the configuration files required to get sendmail+IDA sources to compile,
install, and run under \linux{} are included in \file{newspak-2.2.tar.gz}
which is available via anonymous FTP on \host{sunsite.unc.edu} in the
directory \file{/pub/Linux/system/Mail}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Overview of the tables
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Configuration Files --- Overview}
\index{IDA|see {\prog{sendmail}, IDA}}

\index{sendmail@\prog{sendmail}!CF}
Traditional sendmail is set up through a system configuration file (typically
\file{/etc/sendmail.cf} or \file{/usr/lib/sendmail.cf}), that is not anything
close to any language you've seen before. Editing the \file{sendmail.cf} file
to provide customized behavior can be a humbling experience.


\index{sendmail@\prog{sendmail}!IDA}
Sendmail+IDA makes such pain essentially a thing of the past by having all
configuration options table-driven with rather easy to understand syntax.
These options are configured by running \prog{m4} (a macro processor) or
\prog{dbm} (a database processor) on a number of data files via Makefiles
supplied with the sources.


\index{sendmail@\prog{sendmail}!tables}
The \file{sendmail.cf} file defines only the default behavior of the system.
Virtually all special customization is done through a number of optional
tables rather than by directly editing the \file{sendmail.cf} file.  A list
of all \prog{sendmail} tables is given in figure~\ref{sendmail.fig.tables}.

%%
%% Andy would like this in a table so people can find it in the TOC
%%
%% I don't think this looks too great.  Maybe the figure needs to
%% be boxed or something but whatever y'all want is ok with me - vds
%%
\begin{figure}[htbp]
  \begin{quote}
  \begin{dispitems}
  \item[\file{mailertable}]
	defines special behavior for remote hosts or domains.
  \item[\file{uucpxtable}]
	forces UUCP delivery of mail to hosts that are in DNS format.
  \item[\file{pathtable}]
	defines UUCP bang-paths to remote hosts or domains.
  \item[\file{uucprelays}]
	short-circuits the pathalias path to well-known remote hosts.
  \item[\file{genericfrom}]
	converts internal addresses into generic ones visible to the
	outside world.
  \item[\file{xaliases}]
	converts generic addresses to/from valid internal ones.
  \item[\file{decnetxtable}]
	converts RFC-822 addresses to DECnet-style addresses.
  \end{dispitems}
  \end{quote}
  \caption{
   \label{sendmail.fig.tables}
   \prog{sendmail} Support Files.
  }
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sendmail.cf - general description
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The \file{sendmail.cf}  File}
\index{sendmail@\prog{sendmail}!CF|(}

The \file{sendmail.cf} file for sendmail+IDA is not edited directly, but is
generated from an \prog{m4} configuration file provided by the local system
administrator. In the following, we will refer to it as \file{sendmail.m4}.

This file contains a few definitions and otherwise merely points to the
tables where the real work gets done.   In general, it is only necessary to
specify:

\begin{itemize}
\item
      the pathnames and filenames used on the local system.
\item
      the name(s) the site is known by for e-mail purposes.
\item
      which default mailer (and perhaps smart relay host) is desired.
\end{itemize}

There are a large variety of parameters that can be defined to establish the
behavior of the local site or to override compiled-in configuration items.
These configuration options are identified in the file
\file{ida/cf/OPTIONS} in the source directory.

A \file{sendmail.m4} file for a minimal configuration (UUCP or SMTP
with all non-local mail being relayed to a directly connected
smart-host) can be as short as 10 or 15 lines excluding comments.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% sendmail.cf - example
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{An Example \file{sendmail.m4} File}

A \file{sendmail.m4} file for \host{vstout} at the Virtual Brewery is shown
below.  \host{vstout} uses SMTP to talk to all hosts on the Brewery's LAN,
and sends all mail for other destinations to \host{moria}, its Internet relay
host, via UUCP.

%%%
%%% Olaf, I'm not so certain that this .m4 is correct.  From what I read
%%% in your edits, you have a host that talks SMTP on the local LAN
%%% and that talks UUCP to a relay host for the rest of the world.
%%% If that's the case, I'm not certain if we want a DEFAULT_MAILER
%%% set to TCP here added to the following example that sets the
%%% UUCP-based RELAY_MAILER/RELAY_HOST stuff.
%%% Unfortunately, I have no way to test this here.
%%%
%%% -- I checked this out using the file below with Rich Braun's
%%% sendmail5.65c port. Mail to sites in /etc/hosts gets delivered
%%% via TCP by default.   -okir


\begin{figure}[tbp]
\small
\begin{verbatim}
dnl #------------------ SAMPLE SENDMAIL.M4 FILE ------------------
dnl # (the string 'dnl' is the m4 equivalent of commenting out a line)
dnl # you generally don't want to override LIBDIR from the compiled in paths
dnl #define(LIBDIR,/usr/local/lib/mail)dnl    # where all support files go
define(LOCAL_MAILER_DEF, mailers.linux)dnl    # mailer for local delivery
define(POSTMASTERBOUNCE)dnl                   # postmaster gets bounces
define(PSEUDODOMAINS, BITNET UUCP)dnl         # don't try DNS on these
dnl #-------------------------------------------------------------
dnl #
define(PSEUDONYMS, vstout.vbrew.com  vstout.UUCP vbrew.com)
dnl                                           # names we're known by
define(DEFAULT_HOST, vstout.vbrew.com)dnl     # our primary 'name' for mail
define(UUCPNAME, vstout)dnl                   # our uucp name
dnl #
dnl #-------------------------------------------------------------
dnl #
define(UUCPNODES, |uuname|sort|uniq)dnl       # our uucp neighbors
define(BANGIMPLIESUUCP)dnl                    # make certain that uucp
define(BANGONLYUUCP)dnl                       #  mail is treated correctly
define(RELAY_HOST, moria)dnl                  # our smart relay host
define(RELAY_MAILER, UUCP-A)dnl               # we reach moria via uucp
dnl #
dnl #--------------------------------------------------------------------
dnl #
dnl # the various dbm lookup tables
dnl #
define(ALIASES, LIBDIR/aliases)dnl            # system aliases
define(DOMAINTABLE, LIBDIR/domaintable)dnl    # domainize hosts
define(PATHTABLE, LIBDIR/pathtable)dnl        # paths database
define(GENERICFROM, LIBDIR/generics)dnl       # generic from addresses
define(MAILERTABLE, LIBDIR/mailertable)dnl    # mailers per host or domain
define(UUCPXTABLE, LIBDIR/uucpxtable)dnl      # paths to hosts we feed
define(UUCPRELAYS, LIBDIR/uucprelays)dnl      # short-circuit paths
dnl #
dnl #--------------------------------------------------------------------
dnl #
dnl # include the 'real' code that makes it all work
dnl # (provided with the source code)
dnl #
include(Sendmail.mc)dnl                         # REQUIRED ENTRY !!!
dnl #
dnl #------------ END OF SAMPLE SENDMAIL.M4 FILE -------
\end{verbatim}
\caption{
 \label{sendmail.fig.m4}
 A sample \file{sendmail.m4} file for \host{vstout}.
}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Typically Used \file{sendmail.m4} Parameters}

A few or the items in the \file{sendmail.m4} file are required all the
time; others can be ignored if you can get away with defaults.  The
following sections describe each of the items in the example
\file{sendmail.m4} file in more detail.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Items that Define Paths}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{tscreen}
\begin{verbatim}
dnl #define(LIBDIR,/usr/local/lib/mail)dnl  # where all support files go
\end{verbatim}
\end{tscreen}

\keyword{LIBDIR} defines the directory where sendmail+IDA expects to
find configuration files, the various dbm tables, and special local
definitions.  In a typical binary distribution, this is compiled into
the sendmail binary and does not need to be explicitly set in the
sendmail.m4 file.

The above example has a leading \keyword{dnl} which means that this line
is essentially a comment for information only.

To change the location of the support files to a different location,
remove the leading \keyword{dnl} from the above line, set the path to the
desired location, and rebuild and reinstall the \file{sendmail.cf} file.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Defining the Local Mailer}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{sendmail@\prog{sendmail}!transport|see \prog{sendmail}, mailers}
\index{sendmail@\prog{sendmail}!mailers}

\begin{tscreen}
\begin{verbatim}
define(LOCAL_MAILER_DEF, mailers.linux)dnl  # mailer for local delivery
\end{verbatim}
\end{tscreen}

Most operating systems provide a program to handle local delivery of mail.
Typical programs for many of the major variants of Unix are already built into
the sendmail binary.

In \linux, it is necessary to explicitly define the appropriate local mailer
since a local delivery program is not necessarily present in the distribution
you've installed.  This is done by specifying \keyword{LOCAL\_MAILER\_DEF} in the
\file{sendmail.m4} file.

\index{sendmail@\prog{sendmail}!deliver@\prog{deliver}}
For example, to have the commonly used \prog{deliver} program\footnote{
  \prog{deliver} was written by Chip Salzenberg (\email{chip\%tct@ateng.com}).
  It is part of several \linux{} distributions and can be found in the
  usual anonymous FTP archives such as \host{ftp.uu.net}.
} provide this service, you would set \keyword{LOCAL\_MAILER\_DEF} to
\file{mailers.linux}.

The following file should then be installed as \file{mailers.linux} in
the directory pointed to by \keyword{LIBDIR}.  It explicitly defines the
\prog{deliver} program in the internal \keyword{Mlocal} mailer with the
proper parameters to result in \prog{sendmail} correctly delivering mail
targeted for the local system.  Unless you are a sendmail expert, you
probably do not want to alter the following example.

\begin{tscreen}
\begin{verbatim}
# -- /usr/local/lib/mail/mailers.linux --
#     (local mailers for use on Linux )
Mlocal, P=/usr/bin/deliver, F=SlsmFDMP, S=10, R=25/10, A=deliver $u
Mprog,  P=/bin/sh,       F=lsDFMeuP,   S=10, R=10, A=sh -c $u
\end{verbatim}
\end{tscreen}

%%
%% The following works, but the linux file system standards are
%% different from the sendmail+IDA idea of 'proper'.  I mention it because
%% it'll surprise people if they read the docs in the sendmail+IDA sources
%% and merely use the built-in definition for 'deliver'. Fortunately I
%% run here with syslog so I had a log file to show me why the mail was
%% disappearing. Since it's important for people to NOT edit the Sendmail.mc
%% file, I thought it was worth mentioning here. (vds 3/11)
%%

There is a also built-in default for \prog{deliver} in the \file{Sendmail.mc}
file that gets included into the \file{sendmail.cf} file.
To specify it, you would not use the mailers.linux file and would
instead define the following in your \file{sendmail.m4} file:

\begin{tscreen}
\begin{verbatim}
dnl --- (in sendmail.m4) ---
define(LOCAL_MAILER_DEF, DELIVER)dnl       # mailer for local delivery
\end{verbatim}
\end{tscreen}

Unfortunately, \file{Sendmail.mc} assumes deliver is installed in
\file{/bin}, which is not the case with Slackware1.1.1 (which installs
it in \file{/usr/bin}).  In that case you'd need to either fake it with
a link or rebuild deliver from sources so that it resides in
\file{/bin}.

%%
%% Merely moving the binary for 'deliver' may result in 'unexpected features'
%%
%% Editing Sendmail.mc to set the path to match the Linux distribution is
%% something that's easy to forget to do as the sendmail+IDA authors come out
%% with updates of the file to fix problems, add features, etc.
%%
%% Defining a LOCAL_MAILER_DEF file is the safest compromise...
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Dealing with Bounced Mail}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{sendmail@\prog{sendmail}!postmaster@\user{postmaster}}
\index{mail!bounce}

\begin{tscreen}
\begin{verbatim}
define(POSTMASTERBOUNCE)dnl                # postmaster gets bounces
\end{verbatim}
\end{tscreen}

Many sites find that it is important to ensure that mail is sent and received
with close to a 100\% success rate.  While examining \prog{syslogd(8)} logs
is helpful, the local mail administrator generally needs to see the headers
on bounced mail in order to determine if the mail was undeliverable because
of user error or a configuration error on one of the systems involved.

Defining \keyword{POSTMASTERBOUNCE} results in a copy of each bounced message
being set to the person defined as \user{Postmaster} for the system.

Unfortunately, setting this parameter also results in the \emph{text} of the
message being sent to the Postmaster, which potentially has related privacy
concerns for people using mail on the system.

Site postmasters should in general attempt to discipline themselves (or do so
via technical means through shell scripts that delete the text of the bounce
messages they receive) from reading mail not addressed to them.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Domain Name Service Related Items}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{tscreen}
\begin{verbatim}
define(PSEUDODOMAINS, BITNET UUCP)dnl       # don't try DNS on these
\end{verbatim}
\end{tscreen}

There are several well known networks that are commonly referenced in mail
addresses for historical reasons but that are not valid for DNS purposes.
Defining \keyword{PSEUDODOMAINS} prevents needless DNS lookup attempts that will
always fail.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Defining Names the Local System is Known by}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{sendmail@\prog{sendmail}!local hostnames}

\begin{tscreen}
\begin{verbatim}
define(PSEUDONYMS, vstout.vbrew.com  vstout.UUCP vbrew.com)
dnl                                         # names we're known by
define(DEFAULT_HOST, vstout.vbrew.com)dnl   # our primary 'name' for mail
\end{verbatim}
\end{tscreen}

Frequently, systems wish to hide their true identity, serve as mail gateways,
or receive and process mail addressed to `old' names by which they used to be
known.

\keyword{PSEUDONYMS} specifies the list of all hostnames for which the local
system will accept mail.

\keyword{DEFAULT\_HOST} specifies the hostname that will appear in messages
originating on the local host.  It is important that this parameter be set
to a valid value or all return mail will be undeliverable.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{UUCP-Related Items}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{sendmail@\prog{sendmail}!local hostnames}
\index{sendmail@\prog{sendmail}!UUCP}

%%
%%  yes, the '|' before the uuname command is correct
%%

\begin{tscreen}
\begin{verbatim}
define(UUCPNAME, vstout)dnl                 # our uucp name
define(UUCPNODES, |uuname|sort|uniq)dnl     # our uucp neighbors
define(BANGIMPLIESUUCP)dnl                  # make certain that uucp
define(BANGONLYUUCP)dnl                     #  mail is treated correctly 
\end{verbatim}
\end{tscreen}

Frequently, systems are known by one name for DNS purposes and another for
UUCP purposes.  \keyword{UUCPNAME} permits you to define a different hostname that
appears in the headers of outgoing UUCP mail.

\keyword{UUCPNODES} defines the commands that return a list of hostnames for the 
systems we are connected directly to via UUCP connections.

\keyword{BANGIMPLIESUUCP} and \keyword{BANGONLYUUCP} ensure that mail addressed with
UUCP `bang' syntax is treated according to UUCP behavior rather than the more
current Domain Name Service behavior used today on Internet.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Relay Systems and Mailers}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{sendmail@\prog{sendmail}!routing!smart-host}
\index{sendmail@\prog{sendmail}!relay host}
\index{sendmail@\prog{sendmail}!mailers}

\begin{tscreen}
\begin{verbatim}
define(RELAY_HOST, moria)dnl                # our smart relay host
define(RELAY_MAILER, UUCP-A)dnl             # we reach moria via UUCP
\end{verbatim}
\end{tscreen}

Many system administrators do not want to be bothered with the work needed to
ensure that their system is able to reach all the networks (and therefore
systems) on all networks worldwide.  Instead of doing so, they would rather
relay all outgoing mail to another system that is known to be indeed
``smart''.

\keyword{RELAY\_HOST} defines the UUCP hostname of such a smart neighboring
system.

\keyword{RELAY\_MAILER} defines the mailer used to relay the messages there.

It is important to note that setting these parameters results in your outgoing
mail being forwarded to this remote system, which will affect the load of
their system.  Be certain to get explicit agreement from the remote Postmaster
before you configure your system to use another system as a general purpose
relay host.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The Various Configuration Tables}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{sendmail@\prog{sendmail}!tables}

\begin{tscreen}
\begin{verbatim}
define(ALIASES, LIBDIR/aliases)dnl          # system aliases
define(DOMAINTABLE, LIBDIR/domaintable)dnl  # domainize hosts
define(PATHTABLE, LIBDIR/pathtable)dnl      # paths database
define(GENERICFROM, LIBDIR/generics)dnl     # generic from addresses
define(MAILERTABLE, LIBDIR/mailertable)dnl  # mailers per host or domain
define(UUCPXTABLE, LIBDIR/uucpxtable)dnl    # paths to hosts we feed
define(UUCPRELAYS, LIBDIR/uucprelays)dnl    # short-circuit paths
\end{verbatim}
\end{tscreen}

With these macros, you can change the location where sendmail+IDA looks
for the various dbm tables that define the system's ``real'' behavior.
It is generally wise to leave them in \keyword{LIBDIR}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{The Master \file{Sendmail.mc} File}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{tscreen}
\begin{verbatim}
include(Sendmail.mc)dnl                     # REQUIRED ENTRY !!!
\end{verbatim}
\end{tscreen}

The authors of sendmail+IDA provide the \file{Sendmail.mc} file which contains
the true ``guts'' of what becomes the sendmail.cf file.  Periodically, new
versions are released to fix bugs or add functionality without requiring a
full release and recompilation of sendmail from sources.

It is important \emph{not} to edit this file.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{So Which Entries are Really Required?}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{sendmail@\prog{sendmail}!CF}

When not using any of the optional dbm tables, sendmail+IDA delivers mail via
the \keyword{DEFAULT\_MAILER} (and possibly \keyword{RELAY\_HOST} and
\keyword{RELAY\_MAILER}) defined in the \file{sendmail.m4} file used to
generate \file{sendmail.cf}.  It is easily possible to override this behavior
through entries in the \file{domaintable} or \file{uucpxtable}.


\index{sendmail@\prog{sendmail}!Internet site}
\index{sendmail@\prog{sendmail}!UUCP leaf site}
A generic site that is on Internet and speaks Domain Name Service, or one
that is UUCP-only and forwards all mail via UUCP through a smart
\keyword{RELAY\_HOST}, probably does not need any specific table entries at
all.


Virtually all systems should set the \keyword{DEFAULT\_HOST} and
\keyword{PSEUDONYMS} macros, which define the canonical site name and aliases
it is known by, and \keyword{DEFAULT\_MAILER}. If all you have is a relay
host and relay mailer, you don't need to set these defaults since it works
automagically.


UUCP hosts will probably also need to set \keyword{UUCPNAME} to their
official UUCP name.  They will also probably set \keyword{RELAY\_MAILER}, and
\keyword{RELAY\_HOST} which enable smart-host routing through a mail relay.
The mail transport to be used is defined in \keyword{RELAY\_MAILER} and
should usually be \keyword{UUCP-A} for UUCP sites.


If your site is SMTP-only and talks `Domain Name Service', you would change
the \keyword{DEFAULT\_MAILER} to \keyword{TCP-A} and probably delete the
\keyword{RELAY\_MAILER} and \keyword{RELAY\_HOST} lines.

\index{sendmail@\prog{sendmail}!CF|)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% All IDA tables
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{A Tour of Sendmail+IDA Tables}


Sendmail+IDA provides a number of tables that allow you to override the
default behavior of sendmail (specified in the \file{sendmail.m4}
file) and define special behavior for unique situations, remote
systems, and networks.  These tables are post-processed with
\prog{dbm} using the Makefile provided with the distribution.


Most sites will need few, if any, of these tables.  If your site does not
require these tables, the easiest thing is probably to make them zero length
files (with the \prog{touch} command) and use the default Makefile in
\keyword{LIBDIR} rather than editing the Makefile itself.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\file{mailertable}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{sendmail@\prog{sendmail}!mailertable@\file{mailertable}}
\index{sendmail@\prog{sendmail}!mailers}

The \file{mailertable} defines special treatment for specific hosts or domains
based on the remote host or network name.  It is frequently used on Internet
sites to select an intermediate mail relay host or gateway to reach a remote
network through, and to specify a particular protocol (UUCP or SMTP) to be used.
UUCP sites will generally not need to use this file.

Order is important.  Sendmail reads the file top-down and processes the message
according to the first rule it matches. So it is generally wise to place the
most explicit rules at the top of the file and the more generic rules below.

Suppose you want to forward all mail for the Computer Science department
at Groucho Marx University via UUCP to a relay host \host{ada}.    To
do so, you would have a \file{mailertable} entry that looked like the
following:

\begin{tscreen}
\begin{verbatim}
 # (in mailertable)
 #
 # forward all mail for the domain .cs.groucho.edu via UUCP to ada
 UUCP-A,ada         .cs.groucho.edu
\end{verbatim}
\end{tscreen}

Suppose you want all mail to the larger \host{groucho.edu} domain to go to a
different relayhost \host{bighub} for address resolution and delivery.  The
expanded mailertable entries would look quite similar.

\begin{tscreen}
\begin{verbatim}
 # (in mailertable)
 #
 # forward all mail for the domain cs.groucho.edu via UUCP to ada
 UUCP-A,ada         .cs.groucho.edu
 #
 # forward all mail for the domain groucho.edu via UUCP to bighub
 UUCP-A,bighub      .groucho.edu
\end{verbatim}
\end{tscreen}

As mentioned above, order is important.  Reversing the order of the two rules
shown above will result in all mail to \host{.cs.groucho.edu} going through the
more generic \host{bighub} path instead of the explicit \host{ada} path that is
really desired.

\begin{tscreen}
\begin{verbatim}
 # (in mailertable)
 #
 # forward all mail for the domain .groucho.edu via UUCP to bighub
 UUCP-A,bighub     .groucho.edu
 #
 # (it is impossible to reach the next line because 
 #    the rule above will be matched first) 
 UUCP-A,ada        .cs.groucho.edu
 #
\end{verbatim}
\end{tscreen}

%
% Mailertable Format
%

In the mailertable examples above, the \keyword{UUCP-A} mailer makes
\prog{sendmail} use UUCP delivery with domainized headers.

The comma between the mailer and remote system tells it to forward the message
to \host{ada} for address resolution and delivery.

Mailertable entries are of the format:

\begin{tscreen}\sl
 mailer delimiter relayhost\hspace{3cm} host\_or\_domain
\end{tscreen}

There are a number of possible mailers.  The differences are generally in how
they treat addresses.  Typical mailers are \keyword{TCP-A} (TCP/IP with
Internet-style addresses), \keyword{TCP-U} (TCP/IP with UUCP-style
addresses), and \keyword{UUCP-A} (UUCP with Internet-style addresses).


The character that separates the mailer from the host portion on the
left-hand-side of a mailertable line defines how the address is modified by
the mailertable.  The important thing to realize is that this only rewrites
the envelope (to get the mail into the remote system).  Rewriting anything
other than the envelope is generally frowned upon due to the high probability
of breaking the mail configuration.

%%
%% 'envelope' needs to be mentioned in the overall mail chapter 
%% 

\begin{dispitems}
\item[!]
	An exclamation point strips off the recipient hostname before
	forwarding to the mailer.   This can be used when you want to wish to
	essentially force mail into a misconfigured remote site.

\item[,]
	A comma does not change the address in any way.
	The message is merely forwarded via the specified
	mailer to the specified relay host.

%%
%% Andy - I've never found a reason to use ':' in real life
%%        and very rarely need to use '!'. [...vds...]
%%

\item[:]
	A colon removes the recipient hostname only if there are
	intermediate hosts between you and the destination.
	Thus, \email{foo!bar!joe} will have \email{foo} removed, while
	\email{xyzzy!janet} will remain unchanged.
\end{dispitems}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\file{uucpxtable}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{sendmail@\prog{sendmail}!fully qualified domain name}
\index{sendmail@\prog{sendmail}!unqualified hostname}
\index{sendmail@\prog{sendmail}!routing!UUCP}
\index{sendmail@\prog{sendmail}!mailers}
\index{sendmail@\prog{sendmail}!UUCP}

Usually, mail to hosts with fully-qualified domain names is delivered via
Internet style (SMTP) delivery using Domain Name Service (DNS), or via the
relay host.  The \file{uucpxtable} forces delivery via UUCP routing by
converting the domainized name into a UUCP-style un-domainized remote
hostname.

It is frequently used when you're a mail forwarder for a site or domain or
when you wish to send mail via a direct and reliable UUCP link rather than
potentially multiple hops through the default mailer and any intermediate
systems and networks.

UUCP sites that talk to UUCP neighbors who use domainized mail headers would
use this file to force delivery of the mail through the direct UUCP
point-to-point link between the two systems rather than using the less direct
route through the \keyword{RELAY\_MAILER} and \keyword{RELAY\_HOST} or
through the \keyword{DEFAULT\_MAILER}.

Internet sites who do not talk UUCP probably would not use the
\file{uucpxtable}.

Suppose you provide mail forwarding service to a system called
\host{sesame.com} in DNS and \host{sesame} in the UUCP maps.  You would need
the following \file{uucpxtable} entry to force mail for their host to go
through your direct UUCP connection.

\begin{tscreen}
\begin{verbatim}
#============== /usr/local/lib/mail/uucpxtable ============
# Mail sent to joe@sesame.com is rewritten to sesame!joe and 
# therefore delivered via UUCP
#
sesame   	sesame.com
#
#----------------------------------------------------------
\end{verbatim}
\end{tscreen}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\file{pathtable}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{sendmail@\prog{sendmail}!routing}

The \file{pathtable} is used to define explicit routing to remote hosts or
networks. The \file{pathtable} file should be in pathalias-style syntax,
sorted alphabetically.  The two fields on each line must be separated by a
real TAB, else \prog{dbm} might complain.

Most systems will not need any \file{pathtable} entries.

%%
%%  need to define %s in the pathtable.  Olaf - can you please check it
%%  out in the pathalias man page if you have it around. My recollection
%%  is that it's effectively "any username"
%%

\begin{tscreen}
\begin{verbatim}
#=============== /usr/local/lib/mail/pathtable ================
#
# this is a pathalias-style paths file to let you kick mail to 
# UUCP neighbors to the direct UUCP path so you don't have to
# go the long way through your smart host that takes other traffic
#
# you want real tabs on each line or m4 might complain
#
# route mail through one or more intermediate sites to a remote 
# system using UUCP-style addressing.
#
sesame!ernie!%s            ernie
#	
# forwarding to a system that is a UUCP neighbor of a reachable
# internet site.
#
swim!%s@gcc.groucho.edu    swim
#
# The following sends all mail for two networks through different
# gateways (see the leading '.' ?).
# In this example, "uugate" and "byte" are specific systems that serve
# as mail gateways to the .UUCP and .BITNET pseudo-domains respectively
#
%s@uugate.groucho.edu           .UUCP
byte!%s@mail.shift.com          .BITNET
#
#=================== end of pathtable =======================
\end{verbatim}
\end{tscreen}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\file{domaintable}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{sendmail@\prog{sendmail}!fully qualified domain name}
\index{sendmail@\prog{sendmail}!unqualified hostname}
\index{sendmail@\prog{sendmail}!mailers}

The \file{domaintable} is generally used to force certain behavior after a
DNS lookup has occurred.  It permits the administrator to make shorthand
names available for commonly referenced systems or domains by replacing the
shorthand name with the proper one automatically.  It can also be used to
replace incorrect host or domain names with the ``correct'' information.

Most sites will not need any \file{domaintable} entries.

The following example shows how to replace an incorrect address people are
attempting to mail to with the correct address:

\begin{tscreen}
\begin{verbatim}
#============= /usr/local/lib/mail/domaintable =================
#
#
brokenhost.correct.domain         brokenhost.wrong.domain
#
#
#=================== end of domaintable ========================
\end{verbatim}
\end{tscreen}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\file{aliases}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{sendmail@\prog{sendmail}!writing mail to a file}
\index{sendmail@\prog{sendmail}!user aliases}
\index{sendmail@\prog{sendmail}!aliases}

Aliases permit a number of things to happen:

\begin{itemize}
\item
	They provide a shorthand or well-known name for mail to be addressed
	to in order to go to one or more persons.
\item
	They invoke a program with the mail message as the input to the
	program.
\item
	They send mail to a file.
\end{itemize}

\index{sendmail@\prog{sendmail}!postmaster}
All systems require aliases for \user{Postmaster} and \user{MAILER-DAEMON} to
be RFC-compliant.

Always be extremely aware of security when defining aliases that invoke
programs or write to programs since sendmail generally runs setuid-root.

Changes to the \file{aliases} file do not take effect until the command

\begin{tscreen}
 \# /usr/lib/sendmail -bi
\end{tscreen}

\noindent
is executed to build the required dbm tables.  This can also be done by
executing the \prog{newaliases} command, usually from cron.

Details concerning mail aliases may be found in the \file{aliases(5)} manual
page.

\begin{tscreen}
\begin{verbatim}
#--------------------- /usr/local/lib/mail/aliases ------------------
#
# demonstrate commonly seen types of aliases
#
usenet:         janet                     # alias for a person
admin:          joe,janet                 # alias for several people
newspak-users:  :include:/usr/lib/lists/newspak
                                          # read recipients from a file
changefeed:     | /usr/local/lib/gup      # alias that invokes a program
complaints:     /var/log/complaints       # alias that writes mail to a file
#
# The following two aliases must be present to be RFC-compliant. 
# It is important to have them resolve to 'a person' who reads mail routinely.
#
postmaster:     root                      # required entry
MAILER-DAEMON:  postmaster                # required entry
#
#-------------------------------------------------------------------
\end{verbatim}
\end{tscreen}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Rarely Used Tables}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{sendmail@\prog{sendmail}!tables}

The following tables are available, but rather infrequently used.  Consult
with the documentation that comes with the sendmail+IDA sources for details.

\begin{dispitems}
\item[\file{uucprelays}]
	\index{sendmail@\prog{sendmail}!routing!UUCP}
	The \file{uucprelays} file is used to ``short-circuit'' the UUCP path
	to especially well known sites rather than using a multi-hop or
	unreliable path generated by processing the UUCP maps with
	\file{pathalias}.

\item[\file{genericfrom} and \file{xaliases}]
	\index{sendmail@\prog{sendmail}!user aliases}
	The \file{genericfrom} file hides local usernames and addresses from
	the outside world by automatically converting local usernames to
	generic sender addresses that do not match internal usernames.

	The associated \file{xalparse} utility automates the generation of
	the genericfrom and aliases file so that both incoming and outgoing
	username translations occur from a master xaliases file.

\item[\file{decnetxtable}]
	\index{sendmail@\prog{sendmail}!DECnet}
	The \file{decnetxtable} rewrites domainized addresses into
	decnet-style addresses much like the domaintable can be used to
	rewrite undomainized addresses into domainized SMTP-style addresses.

\end{dispitems}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% How to install and test sendmail+IDA                     %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Installing \prog{sendmail}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{sendmail@\prog{sendmail}!installing}

In this section, we'll take a look at how to install a typical binary
distribution of sendmail+IDA, and walk through what needs to be done to make
it localized and functional.


The current binary distribution of sendmail+IDA for \linux{} can be
gotten from \host{sunsite.unc.edu} in \file{/pub/Linux/system/Mail}.
Even if you have an earlier version of \prog{sendmail} I strongly recommend
you go to the \prog{sendmail5.67b+IDA1.5} version since all required
Linux-specific patches are now in the vanilla sources and several
significant security holes have been plugged that were in versions
prior to about December 1, 1993.


\index{sendmail@\prog{sendmail}!version}
%% Hope I'm interpreting you right that there's no binary distribution
%% of sendmail5.67b+IDA1.5
If you are building \prog{sendmail} from the sources, you should
follow the instructions in the \file{README}s included in the source
distribution.  The current sendmail+IDA source is available from
\host{vixen.cso.uiuc.edu}.
To build sendmail+IDA on \linux{}, you also need the \linux-specific
configuration files from \file{newspak-2.2.tar.gz}, which is available on
\host{sunsite.unc.edu} in the \file{/pub/Linux/system/Mail} directory.


If you have previously installed \prog{smail} or another mail
delivery agent, you'll probably want to remove (or rename) all the
files from smail to be safe.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Extracting the binary distribution}

First, you have to unpack the archive file in some safe location:

\begin{tscreen}
\begin{verbatim}
$ gunzip -c sendmail5.65b+IDA1.5+mailx5.3b.tgz | tar xvf -
\end{verbatim}
\end{tscreen}

If you have a ``modern'' \prog{tar}, for example from a recent Slackware
Distribution, you can probably just do a \term{tar -zxvf \var{filename}.tgz}
and get the same results.


Unpacking the archive creates a directory named
\file{sendmail5.65b+IDA1.5+mailx5.3b}. In this directory, you find a
complete installation of sendmail+IDA plus a binary of the
\prog{mailx} user agent. All file paths below this directory reflect
the location where the files should be installed, so it's safe to work
up a \prog{tar} command to move 'em over:


\begin{tscreen}
\begin{verbatim}
# cd sendmail5.65b+IDA1.5+mailx5.3b
# tar cf - . | (cd /; tar xvvpoof -)
\end{verbatim}
\end{tscreen}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Building \file{sendmail.cf}}
\index{sendmail@\prog{sendmail}!generating sendmail.cf@generating \file{sendmail.cf}|(}
\index{sendmail@\prog{sendmail}!CF|(}

To build a \file{sendmail.cf} file customized for your site, you have to
write a \file{sendmail.m4} file, and process it with \prog{m4}.
In \file{/usr/local/lib/mail/CF}, you find a sample file called
\file{sample.m4}.  Copy it to \var{yourhostname}\file{.m4}, and edit
it to reflect the situation of your site.


The sample file is set up for a UUCP-only site that has domainized
headers and talks to a smart host.  Sites like this only need to edit
a few items.


In the current section, I will only give a short overview of the
macros you have to change. For a complete description of what they do,
please refer to the earlier discussion of the \file{sendmail.m4}.


\begin{dispitems}
\item[\keyword{LOCAL\_MAILER\_DEF}]
	Define define the file that defines the mailers for local mail
	delivery.  See section ``Defining the Local Mailer'' above for
	what goes in here.

\item[\keyword{PSEUDONYMS}]
	Define all the names your local host is known by. 

\item[\keyword{DEFAULT\_HOST}]
	Put in your fully qualified domain name. This name will appear
	as your hostname in all outgoing mail.

\item[\keyword{UUCPNAME}]
	Put in your unqualified hostnmae.

\item[\keyword{RELAY\_HOST} and \keyword{RELAY\_MAILER}]
	If you talk UUCP to a smart-host, set \keyword{RELAY\_HOST} to
	the UUCP name of your `smart relay' uucp neighbor.  Use the
	UUCP-A mailer if you want domainized headers.

\item[\keyword{DEFAULT\_MAILER}]
	If you are on Internet and talk DNS, you should set this to
	\keyword{TCP-A}.  This tells sendmail to use the \keyword{TCP-A}
	mailer, which delivers mail via SMTP using normal RFC style
	addressing for the envelope.  Internet sites probably do not need
	to define \keyword{RELAY\_HOST} or \keyword{RELAY\_MAILER}.

\end{dispitems}


To create the \file{sendmail.cf} file, execute the command

\begin{tscreen}
\#{} make \var{yourhostname}.cf
\end{tscreen}

This processes the \var{yourhostname}\file{.m4} file and creates
\var{yourhostname}\file{.cf} from it.


Next, you should test whether the configuration file you've created
does what you expect it to do.  This is explained in the following two
sections.

Once you're happy with its behavior, copy it into place with the
command:

\begin{tscreen}
\#{} cp \var{yourhostname}\/.cf /etc/sendmail.cf
\end{tscreen}

\index{sendmail@\prog{sendmail}!generating sendmail.cf@generating \file{sendmail.cf}|)}
\index{sendmail@\prog{sendmail}!CF|)}

\index{server!sendmail@\prog{sendmail}}
\index{sendmail@\prog{sendmail}!running}
At this point, your sendmail system is ready for action.  Put the following
line in the appropriate startup file (generally \file{/etc/rc.inet2}).  You
can also execute it by hand to have the process start up now.


\begin{tscreen}
\begin{verbatim}
# /usr/lib/sendmail -bd -q1h
\end{verbatim}
\end{tscreen}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%    putting sendmail in \test mode   %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection {Testing the \file{sendmail.cf} file}
\index{sendmail@\prog{sendmail}!testing|(}
\index{checking!sendmail@\prog{sendmail}|(}

%%%%%
%%%%% aaaahhhhhhhhhhh - those darn dashes are driving me crazy.
%%%%%

To put sendmail into `test' mode, you invoke it with the \option{-bt}
flag.  The default configuration file is the sendmail.cf file that is
installed on the system.  You can test an alternate file by using the
\option{-C}\var{filename} option.


In the following examples, we test \file{vstout.cf}, the configuration
file generated from the \file{vstout.m4} file shown in
figure~\ref{sendmail.fig.m4}.

\begin{tscreen}
\begin{verbatim}
# /usr/lib/sendmail -bt -Cvstout.cf
ADDRESS TEST MODE
Enter <ruleset> <address>
[Note: No initial ruleset 3 call]
>
\end{verbatim}
\end{tscreen}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% test that it knows you're you       %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%
%%% there are sure a lot of \item things in this section.
%%% it doesn't look THAT bad, but I wonder...
%%%

The following tests ensure that \prog{sendmail} is able to deliver all
mail to users on your system.  In all cases the result of the test
should be the same and point to the local system name with the
\keyword{LOCAL} mailer.

First test how a mail to a local user would be delivered.

\begin{tscreen}
\begin{verbatim}

# /usr/lib/sendmail -bt -Cvstout.cf
ADDRESS TEST MODE
Enter <ruleset> <address>
[Note: No initial ruleset 3 call]
> 3,0 me
rewrite: ruleset  3   input: me
rewrite: ruleset  7   input: me
rewrite: ruleset  9   input: me
rewrite: ruleset  9 returns: < me >
rewrite: ruleset  7 returns: < > , me
rewrite: ruleset  3 returns: < > , me
rewrite: ruleset  0   input: < > , me
rewrite: ruleset  8   input: < > , me
rewrite: ruleset 20   input: < > , me
rewrite: ruleset 20 returns: < > , @ vstout . vbrew . com , me
rewrite: ruleset  8 returns: < > , @ vstout . vbrew . com , me
rewrite: ruleset 26   input: < > , @ vstout . vbrew . com , me
rewrite: ruleset 26 returns: $# LOCAL $@ vstout . vbrew . com $: me
rewrite: ruleset  0 returns: $# LOCAL $@ vstout . vbrew . com $: me
\end{verbatim}
\end{tscreen}

The output shows how \prog{sendmail} processes the address internally.
It is handed to various rulesets which analyze it, invoke other
rulesets in turn, and break it up into its components.

In our example, we passed the address \email{me} to rulesets 3 and 0
(this is the meaning of the \term{3,0} entered before the address).
The last line shows the parsed address as returned by ruleset 0,
containing the mailer the message would be delivered by, and the host
and user name given to the mailer.


Next, test mail to a user on your system with UUCP syntax.

\begin{tscreen}
\begin{verbatim}

# /usr/lib/sendmail -bt -Cvstout.cf
ADDRESS TEST MODE
Enter <ruleset> <address>
[Note: No initial ruleset 3 call]
> 3,0 vstout!me
rewrite: ruleset  3   input: vstout ! me
[...]
rewrite: ruleset  0 returns: $# LOCAL $@ vstout . vbrew . com  $: me
>

\end{verbatim}
\end{tscreen}

Next, test mail addressed to a user on your system with Internet syntax
to your fully qualified hostname.

\begin{tscreen}
\begin{verbatim}

# /usr/lib/sendmail -bt -Cvstout.cf
ADDRESS TEST MODE
Enter <ruleset> <address>
[Note: No initial ruleset 3 call]
> 3,0 me@vstout.vbrew.com
rewrite: ruleset  3   input: me @ vstout . vbrew . com
[...]
rewrite: ruleset  0 returns: $# LOCAL $@ vstout . vbrew . com $: me
>

\end{verbatim}
\end{tscreen}


You should repeat the above two tests with each of the names you
specified in the \keyword{PSEUDONYMS} and \keyword{DEFAULT\_NAME}
parameters in your \file{sendmail.m4} file.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% test that your relay_host and relay_mailer work %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Lastly, test that you can mail to your relay host.

\begin{tscreen}
\begin{verbatim}

# /usr/lib/sendmail -bt -Cvstout.cf
ADDRESS TEST MODE
Enter <ruleset> <address>
[Note: No initial ruleset 3 call]
> 3,0 fred@moria.com
rewrite: ruleset  3   input: fred @ moria . com
rewrite: ruleset  7   input: fred @ moria . com
rewrite: ruleset  9   input: fred @ moria . com
rewrite: ruleset  9 returns: < fred > @ moria . com
rewrite: ruleset  7 returns: < @ moria . com > , fred
rewrite: ruleset  3 returns: < @ moria . com > , fred
rewrite: ruleset  0   input: < @ moria . com > , fred
rewrite: ruleset  8   input: < @ moria . com > , fred
rewrite: ruleset  8 returns: < @ moria . com > , fred
rewrite: ruleset 29   input: < @ moria . com > , fred
rewrite: ruleset 29 returns: < @ moria . com > , fred
rewrite: ruleset 26   input: < @ moria . com > , fred
rewrite: ruleset 25   input: < @ moria . com > , fred
rewrite: ruleset 25 returns: < @ moria . com > , fred
rewrite: ruleset  4   input: < @ moria . com > , fred
rewrite: ruleset  4 returns: fred @ moria . com                                               
rewrite: ruleset 26 returns: < @ moria . com > , fred
rewrite: ruleset  0 returns: $# UUCP-A $@ moria $: < @ moria . com > , fred
>

\end{verbatim}
\end{tscreen}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Putting it all together -
	Integration Testing \file{sendmail.cf} and the tables}
\index{sendmail@\prog{sendmail}!tables}

At this point, you've verified that mail will have the desired default
behavior and that you'll be able to both send and received validly
addressed mail.  To complete the installation, it may be necessary to
create the appropriate dbm tables to get the desired final results.

After creating the table(s) that are required for your site, you must
process them through \prog{dbm} by typing \prog{make} in the directory
containing the tables.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%  Do you need tables for your site ?  Maybe...      %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

If you are UUCP-only, you do \emph{not} need to create any of the tables
mentioned in the \file{README.linux} file.  You'll just have to touch
the files so that the Makefile works.

If you're UUCP-only and you talk to sites in addition to your
smart-host, you'll need to add \file{uucpxtable} entries for each (or
mail to them will also go through the smart host) and run \prog{dbm}
against the revised \file{uucpxtable}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% test that your relay_host and relay_mailer work %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
First, you need to make certain that mail through your
\keyword{RELAY\_HOST} is sent to them via the \keyword{RELAY\_MAILER}.

\begin{tscreen}
\begin{verbatim}

# /usr/lib/sendmail -bt -Cvstout.cf
ADDRESS TEST MODE
Enter <ruleset> <address>
[Note: No initial ruleset 3 call]
> 3,0 fred@sesame.com
rewrite: ruleset  3   input: fred @ sesame . com
rewrite: ruleset  7   input: fred @ sesame . com
rewrite: ruleset  9   input: fred @ sesame . com
rewrite: ruleset  9 returns: < fred > @ sesame . com
rewrite: ruleset  7 returns: < @ sesame . com > , fred
rewrite: ruleset  3 returns: < @ sesame . com > , fred
rewrite: ruleset  0   input: < @ sesame . com > , fred
rewrite: ruleset  8   input: < @ sesame . com > , fred
rewrite: ruleset  8 returns: < @ sesame . com > , fred
rewrite: ruleset 29   input: < @ sesame . com > , fred
rewrite: ruleset 29 returns: < @ sesame . com > , fred
rewrite: ruleset 26   input: < @ sesame . com > , fred
rewrite: ruleset 25   input: < @ sesame . com > , fred
rewrite: ruleset 25 returns: < @ sesame . com > , fred
rewrite: ruleset  4   input: < @ sesame . com > , fred
rewrite: ruleset  4 returns: fred @ sesame . com
rewrite: ruleset 26 returns: < @ sesame . com > , fred                                                          
rewrite: ruleset  0 returns: $# UUCP-A $@ moria $: < @ sesame . com > , fred
>
\end{verbatim}
\end{tscreen}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% test that you can mail directly to uucp neighbors %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

If you have UUCP neighbors other than your \keyword{RELAY\_HOST}, you
need to ensure that mail to them has the proper behavior.  Mail
addressed with UUCP-style syntax to a host you talk UUCP with should
go directly to them (unless you explicitly prevent it with a
\file{domaintable} entry). Assume host \host{swim} is a direct
UUCP neighbor of yours. Then feeding \email{swim!fred} to
\prog{sendmail} should produce the following result:

\begin{tscreen}
\begin{verbatim}

# /usr/lib/sendmail -bt -Cvstout.cf
ADDRESS TEST MODE
Enter <ruleset> <address>
[Note: No initial ruleset 3 call]
> 3,0 swim!fred
rewrite: ruleset  3   input: swim ! fred
[...lines omitted...]
rewrite: ruleset  0 returns: $# UUCP $@ swim $: < > , fred
>
\end{verbatim}
\end{tscreen}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% test your uucpxtable entries %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

If you have \file{uucpxtable} entries to force UUCP delivery to
certain UUCP neighbors who send their mail with Internet style
domainized headers, that also needs to be tested.

\begin{tscreen}
\begin{verbatim}

# /usr/lib/sendmail -bt -Cvstout.cf
ADDRESS TEST MODE
Enter <ruleset> <address>
[Note: No initial ruleset 3 call]
> 3,0 dude@swim.2birds.com
rewrite: ruleset  3   input: dude @ swim . 2birds . com
[...lines omitted...]
rewrite: ruleset  0 returns: $# UUCP $@ swim . 2birds $: < > , dude
>

\end{verbatim}
\end{tscreen}


\index{sendmail@\prog{sendmail}!testing|)}
\index{checking!sendmail@\prog{sendmail}|)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Administrivia and Stupid Mail Tricks}

Now that we've discussed the theory of configuring, installing, and testing a
sendmail+IDA system, lets take a few moments to look into things that
\emph{do} happen routinely in the life of a mail administrator.

Remote systems sometimes break.  Modems or phone lines fail, DNS definitions
are set incorrectly due to human error.  Networks go down unexpectedly.  In
such cases, mail administrators need to know how to react quickly,
effectively, and \emph{safely} to keep mail flowing through alternate routes
until the remote systems or service providers can restore normal services.

The rest of this chapter is intended to provide you with the solutions to the
most frequently encountered ``electronic mail emergencies''.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Forwarding Mail to a Relay Host}
\index{sendmail@\prog{sendmail}!routing!domain}
\index{sendmail@\prog{sendmail}!relay host}

To forward mail for a particular host or domain to a designated relay
system, you generally use the \file{mailertable}.

For example, to forward mail for \host{backwood.org} to their UUCP gateway
system \host{backdoor}, you'd put the following entry into \file{mailertable}:

\begin{tscreen}
\begin{verbatim}
 UUCP-A,backdoor   backwood.org
\end{verbatim}
\end{tscreen}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Forcing Mail into Misconfigured Remote Sites}
\index{sendmail@\prog{sendmail}!remote site misconfigured}
\index{sendmail@\prog{sendmail}!forcing mail}

Frequently, Internet hosts will have trouble getting mail into misconfigured
remote sites.  There are several variants of this problem, but the general
symptom is that mail is bounced by the remote system or never gets there at
all.

These problems can put the local system administrator in a bad position
because your users generally don't care that you don't personally administer
every system worldwide (or know how to get the remote administrator to fix
the problem).  They just know that their mail didn't get through to the
desired recipient on the other end and that you're a likely person to complain
to.

A remote site's configuration is their problem, not yours.  In all cases, be
certain to \emph{not} break your site in order to communicate with a
misconfigured remote site. If you can't get in touch with the Postmaster at
the remote site to get them to fix their configuration in a timely manner,
you have two options.

%%
%% Probably it would look better not to itemize this. I usually shy away
%% from itemizing large portions of text
%%
%% (ok with me if you want to reformat it to look better - vds)
%%
\begin{itemize}
\item
	It is generally possible to force mail into the remote system
	successfully, although since the remote system is misconfigured,
	replies on the remote end might not work\ldots but then that's the
	remote administrator's problem.

	You can fix the bad headers in the envelope on your outgoing messages
	only by using a \file{domaintable} entry for their host/domain that
	results in the invalid information being corrected in mail
	originating from your site:

	\begin{tscreen}
	\begin{verbatim}
	 braindead.correct.domain.com        braindead.wrong.domain.com
	\end{verbatim}
	\end{tscreen}

\item
	Frequently, misconfigured sites `bounce' mail back to the sending
	system and effectively say ``that mail isn't for this site'' because
	they do not have their \keyword{PSEUDONYMNS} or equivalent set
	properly in their configuration.  It is possible to totally strip off
	all hostname and domain information from the envelope of messages
	going from your site to them.

	The \keyword{!} in the following \file{mailertable} delivers mail to
	their remote site making it appear to their \prog{sendmail} as if it
	had originated locally on their system.  Note that this changes only
	the envelope address, so the proper return address will still show up
	in the message.

	\begin{tscreen}
	\begin{verbatim}
	 TCP!braindead.correct.domain.com   braindead.wrong.domain.com
	\end{verbatim}
	\end{tscreen}
\end{itemize}

Regardless, even if you get mail into their system, there is no guarantee that
they can reply to your message (they're broken, remember\ldots) but then their
users are yelling at their administrators rather than your users yelling at
you.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Forcing Mail to be Transferred via UUCP}
\index{mail!forcing UUPC delivery}
\index{sendmail@\prog{sendmail}!forcing UUPC delivery}
\index{sendmail@\prog{sendmail}!unqualified hostname}
\index{sendmail@\prog{sendmail}!routing!UUCP}
\index{sendmail@\prog{sendmail}!UUCP}
\index{sendmail@\prog{sendmail}!mailers}

In an ideal world (from the Internet perspective), all hosts have records in
the Domain Name Service (DNS) and will send mail with fully qualified domain
names.

If you happen to talk via UUCP to such a site, you can force mail to go
through the point-to-point UUCP connection rather than through your default
mailer by essentially ``undomainizing'' their hostname through the
\file{uucpxtable}.

To force UUCP delivery to \host{sesame.com}, you would put the following in
your \file{uucpxtable}:

\begin{tscreen}
\begin{verbatim}
 # un-domainize sesame.com to force UUCP delivery
 sesame    sesame.com
\end{verbatim}
\end{tscreen}

The result is that sendmail will then determine (via
\keyword{UUCPNODES} in the \file{sendmail.m4} file) that you are
directly connected to the remote system and will queue the mail for
delivery with UUCP.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Preventing Mail from Being Delivered via UUCP}
\index{mail!preventing UUPC delivery}
\index{sendmail@\prog{sendmail}!preventing UUPC delivery}
\index{sendmail@\prog{sendmail}!unqualified hostname}
\index{sendmail@\prog{sendmail}!routing!UUCP}
\index{sendmail@\prog{sendmail}!UUCP}
\index{sendmail@\prog{sendmail}!mailers}

The opposite condition also occurs. Frequently, systems may have a number of
direct UUCP connections that are used infrequently or that are not as reliable
and always available as the default mailer or relay host.

For example, in the Seattle area there are a number of systems that exchange
the various \linux{} distributions via anonymous UUCP when the distributions
are released.  These systems talk UUCP only when necessary, so it is generally
faster and more reliable to send mail through multiple very reliable hops and
common (and always available) relay hosts.

It is easily possible to prevent UUCP delivery of mail to a host that you are
directly connected to. If the remote system has a fully-qualified domain name,
you can add an entry like this to the \file{domaintable}:

\begin{tscreen}
\begin{verbatim}
 # prevent mail delivery via UUCP to a neighbor
 snorkel.com       snorkel
\end{verbatim}
\end{tscreen}

This will replace any occurence of the UUCP name with the FQDN, and thus
prevent a match by the \keyword{UUCPNODES} line in the \file{sendmail.m4} file.
The result is generally that mail will go via the \keyword{RELAY\_MAILER}
and \keyword{RELAY\_HOST} (or \keyword{DEFAULT\_MAILER}).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Running the Sendmail Queue on Demand}
\index{sendmail@\prog{sendmail}!queue operation}
\index{sendmail@\prog{sendmail}!run the queue}

To process queued messages immediately, merely type '/usr/lib/runq'. This
invokes sendmail with the appropriate options to cause sendmail to run through
the queue of pending jobs immediately rather than waiting for the next
scheduled run.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Reporting Mail Statistics}
\index{sendmail@\prog{sendmail}!statistics}

Many site administrators (and the persons they work for) are interested in the
volume of mail passing to, from, and through the local site.  There are a
number of ways to quantify mail traffic.

\begin{itemize}
\item
	Sendmail comes with a utility called \prog{mailstats} that reads a
	file called \file{/usr/local/lib/mail/sendmail.st} and reports
	the number of messages and number of bytes transferred by each
	of the mailers used in the \file{sendmail.cf} file.   This
	file must be created by the local administrator manually for
	sendmail logging to occur. The running totals are cleared by
	removing and recreating the \file{sendmail.st} file.  One way
	is to do the following:

	\begin{tscreen}
	 \# cp /dev/null /usr/lib/local/mail/sendmail.st
	\end{tscreen}

\item
	Probably the best way to do quality reporting regarding who uses mail
	and how much volume passes to, from, and through the local system is
	to turn on mail debugging with \prog{syslogd(8)}.  Generally, this
	means running the \file{/etc/syslogd} daemon from your system startup
	file (which you should be doing anyway), and adding a line to
	\file{/etc/syslog.conf(5)} that looks something like the following:

	%% Dunno if that's in the standard, but it should defnitely go to /var
	\begin{tscreen}
	\begin{verbatim}
	mail.debug                         /var/log/syslog.mail
	\end{verbatim}
	\end{tscreen}

	If you use \keyword{mail.debug} and get any medium to high mail
	volume, the syslog output can get quite large.  Output files from
	\prog{syslogd} generally need to be rotated or purged on a routine
	basis from \prog{crond(8)}.

	There are a number of commonly available utilities that can summarize
	the output of mail logging from syslogd.  One of the more well known
	utilities is \file{syslog-stat.pl}, a \prog{perl} script that is
	distributed with the sendmail+IDA sources.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Mixing and Matching Binary Distributions}
\index{sendmail@\prog{sendmail}!file locations}

%
% although the Linux File System Standard is developing, it's not 
% universally accepted or implemented yet.  My intent here is to show that
% we're not standard yet and to give them an idea where the likely places
% are where problems may occur
%

There is no true standard configuration of electronic mail transport and
delivery agents and there is no ``one true directory structure.''

Accordingly, it is necessary to ensure that all the various pieces of the
system (USENET news, mail, TCP/IP) agree on the location of the local mail
delivery program (\prog{lmail}, \prog{deliver}, etc.), remote mail delivery
program (\prog{rmail}), and the mail transport program (\prog{sendmail} or
\prog{smail}). Such assumptions are not generally documented, although use of
the \prog{strings} command can help determine what files and directories are
expected.  The following are some problems we've seen in the past with some
of the commonly available \linux{} binary distributions and sources.

\begin{itemize}
\item
	Some versions of the NET-2 distribution of TCP/IP have services
	defined for a program called \prog{umail} rather than
	\prog{sendmail}.

\item
	There are various ports of \prog{elm} and \prog{mailx} that look for
	a delivery agent of \file{/usr/bin/smail} rather than sendmail.

\item
	Sendmail+IDA has a built-in local mailer for \prog{deliver}, but
	expects it to be located in \file{/bin} rather than the more typical
	\linux{} location of \file{/usr/bin}.

\end{itemize}

Rather than go through the trouble of building all the mail clients from
sources, we generally fake it with the appropriate soft links\ldots

%%
%% merely moving 'deliver' from where the Linux binary distribution put it
%% to where sendmail+IDA expects it gets you into a position where you have
%% to remember that you altered your configuration and opens you up to the
%% chances that you may create some 'unexpected features'
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Where to Get More Information}

There are many places you can look for more information on
\prog{sendmail}.  For a list, see the \linux{} MAIL Howto posted
regularly to \ngrp{comp.answers}. It is also available for anonymous
FTP on \host{rtfm.mit.edu}. However, the definitive place is in the
sendmail+IDA sources.  Look in the directory \file{ida/cf} below the
source directory for the files \file{DBM-GUIDE}, \file{OPTIONS}, and
\file{Sendmail.mc}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%
% that's all folks
%

\index{configuring!sendmail@\prog{sendmail}|)}
\index{sendmail@\prog{sendmail}|)}
% \end{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
